home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Tech Notes / Utilities Documentation / Storage Utilites < prev    next >
Encoding:
Text File  |  1995-11-08  |  5.5 KB  |  115 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Utilities Documentation
  2.  
  3. Storage Utilities
  4. by The OpenDoc Design Team
  5.  
  6. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  7. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  8. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  9.  
  10.  
  11. Introduction
  12.  
  13. The storage utilities cover many typical usage of storage system by part editors.
  14.  
  15. Storage Utilities
  16.  
  17.     void        ODSUAddPropValue(Environment* ev,
  18.                     ODStorageUnit* su,
  19.                     ODPropertyName prop,
  20.                     ODValueType val);
  21.  
  22. Given a storage unit, add the specified property and value to the storage unit. If the property or value already exists, it will simply focus the storage unit.
  23.  
  24.     void        ODSUForceFocus(Environment* ev, 
  25.                     ODStorageUnit* su,
  26.                     ODPropertyName prop,
  27.                     ODValueType val);
  28.  
  29. Given a storage unit, this function focuses the storage unit to the specified property and value. If the property or value does not exist, this function will add it to the storage unit.
  30.  
  31.     ODBoolean    ODSUExistsThenFocus(Environment* ev, 
  32.                     ODStorageUnit* su,
  33.                     ODPropertyName prop,
  34.                     ODValueType val);
  35.  
  36. If the part editor calls ODStorageUnit::Focus on a storage unit which does not have the specified property or value, an exception is thrown. One way to avoid this exception is to call ODStorageUnit::Exists to check to see whether the property or value is there before calling ::Focus. This function calls Exists and then Focus to ensure that an exception of such type will not be thrown. If the focus is successful, kODTrue is returned. Otherwise, kODFalse is returned.
  37.  
  38.     void        ODSURemoveProperty(Environment* ev,
  39.                     ODStorageUnit* su,
  40.                     ODPropertyName prop);
  41.  
  42. This procedure removes the specific property from the storage unit.
  43.  
  44.     PlatformFile*    GetPlatformFileFromContainer(Environment* ev, ODContainer* container);
  45.  
  46. This function returns a Platform File object (see Platform File documentation) given a file container. If any container other than a file container is passed in, the behavior is unpredictable. Using this function on a container of an unknown type is not recommended.
  47.  
  48.     ODFileSpec        GetODFileSpecFromContainer(Environment* ev, ODContainer* container);
  49.  
  50. This function is similar to GetPlatformFileFromContainer. The difference is that it returns the file spec, instead of a PlatformFile object.
  51.  
  52.     ODContainer*    CreateFileContainer(Environment* ev, ODSession* session, FSSpec* fsSpec);
  53.  
  54. Given the file spec, this function creates a file container of the default type.
  55.     ODContainer*    GetFileContainer(Environment* ev, ODSession* session, FSSpec* fsSpec);
  56.  
  57. Given the file spec, this function returns a file container which already exists.
  58.  
  59.     ODContainer*    CreateMemoryContainer(Environment* ev,
  60.                         ODSession* session,
  61.                         ODHandle handle,
  62.                         ODContainerType containerType);
  63.  
  64. Given the file spec, this function creates an in-memory container of the specified type.
  65.  
  66.     ODContainer*    GetMemoryContainer(Environment* ev, 
  67.                         ODSession* session,
  68.                         ODHandle handle,
  69.                         ODContainerType containerType);
  70.  
  71. Given the file spec, this function returns an in-memory container of the specified type which already exists.
  72.  
  73.     ODULong            StorageUnitGetValue(ODStorageUnit* su, Environment* ev,
  74.                                         ODULong size, void *buffer);
  75.  
  76. This function gets the data from a value and returns the data in the specified buffer. In this way, the caller does not have to deal with ODByteArray directly. However, this function requires one extra copy. Hence it is not as efficient as using the ODStorageUnit API directly.
  77.  
  78.     ODULong            StorageUnitViewGetValue(ODStorageUnitView* suv, Environment* ev,
  79.                                         ODULong size, void *buffer);
  80.  
  81. This function is similar to StorageUnitGetValue. The difference is that this function works with an ODStorageUnitView object.
  82.  
  83.     void            StorageUnitSetValue(ODStorageUnit* su, Environment* ev,
  84.                                         ODULong size, const void *buffer);
  85.  
  86. This function sets the data in a value given the size and the pointer to a buffer containing the data. In this way, the caller does not have to deal with ODByteArray directly. However, this function requires one extra copy. Hence it is not as efficient as using the ODStorageUnit API directly.
  87.  
  88.     void            StorageUnitViewSetValue(ODStorageUnitView* suv, Environment* ev,
  89.                                         ODULong size, const void *buffer);
  90.  
  91. This function is similar to StorageUnitSetValue. The difference is that this function works with an ODStorageUnitView object.
  92.  
  93.     void            StorageUnitSetPromiseValue(ODStorageUnit* su, Environment* ev,
  94.                             ODValueType value, ODULong offset,
  95.                             ODULong size, const void *buffer, ODPart *sourcePart);
  96.  
  97. This function sets promise data in a value given the size and the pointer to a buffer containing the promise. In this way, the caller does not have to deal with ODByteArray directly. However, this function requires one extra copy. Hence it is not as efficient as using the ODStorageUnit API directly.
  98.  
  99.     ODBoolean        StorageUnitGetStylFromStyledText(ODStorageUnit* su,
  100.                         Environment* ev,
  101.                         ODULong* size,
  102.                         ODPtr* styl);
  103.  
  104. This function returns the size and the data of the style information stored in the contents property of the storage unit.
  105.                         
  106.     ODCloneKind GetOriginalCloneKind(Environment* ev, ODDraft* draft);
  107.  
  108. This function returns the original clone kind of the clone operation. See Data Interchange recipe for its usage.
  109.  
  110.     void RemoveDataInterchangeProperties (Environment* ev,
  111.                         ODStorageUnit* su,
  112.                         ODBoolean clonedToFileContainer);
  113.  
  114. This function removes all the leftover data interchange properties form the storage unit.  See Data Interchange recipe for its usage.
  115.